iziBasic-manual

GUI Statements

Legend:
x is X (left) coordinate, y is Y (top) coordinate, w is Width and h is Height, all of x, y, w and h are v|n.
#v|n is the Object ID and is in the range [1...999]

$ ABOUTBOX c|t1 [+ c|t2] [+ c|t3]

When the user clicks on the Application name, opens your customized AboutBox, otherwise displays the default AboutBox (which says that your application was made with iziBasic)

Notes:

You may pass up to 3 text strings to build an AboutBox with up to 186 characters long (including line feeds)
This statement is overridden by the MENU statement: when the user clicks on the Application name, your menu will be opened instead of the AboutBox
As from version 5.0, the AboutBox can be managed dynamically at runtime and is no more built once at compilation time. This means that you should define your AboutBox after the BEGIN statement to have it taken into account.

ADVICEBOX v|n

Pops up a message window, which has a vertical scroll bar if the text to be displayed requires it, and waits for the user to press the [Done] button.

Notes:

v|n is a message ID as provided in a resource file, the resource being of type tSTR (String resource, please refer to the RESOURCEFILE compiling directive)
v|n is to be in the range [1...999]

BUTTON #v|n, c|t, x, y, w, h

Creates and displays a button with c|t label

CHECKBOX #v|n, c|t, 0|1, x, y, w, h

Creates and displays a checkbox with c|t label and defines if it is initially checked or unchecked (0|1 = unchecked|checked)

$ CLOSEFORM

Closes a custom form and returns to the main form or closes the main form (which is, by default, built and displayed when the program is launched) if no custom form is opened.

Notes:

Closing the main form does not mean that no screen will be displayed; an empty screen is shown instead. If you build GUI objects at this stage, they will not be shown until you open the main form again. But you may draw some "stuff" (see the Graphics module); this "stuff" will be erased when opening back the main form.
See the OPENFORM statement.

$ DESTROY #v|n

Hides an object, inactivates it and destroys it

Notes:

Because of a bug in Palm OS prior to version 4.0 (so in versions 3.x), you should destroy an object before using again the same Object ID. To know which version of Palm OS is on the client device, use the GETOSVER$ function and code consequently (i.e. create even empty objects at the program start, then destroy them just before reusing them), or limit your application with the {MINOSVERSION "4.0"} compiling directive.
Example for Palm OS prior to version 4.0:

LABEL #1,"Hello World",50,50
...
DESTROY #1 : LABEL #1,"Bye, Bye",70,70

For later Palm OS versions (version 4.0 and later), iziBasic handles automatically the reuse of an Object ID by first deleting the previous object and then building the new one, so that you do not have to destroy an object before using again the same Object ID.
Example for Palm OS version 4.0 or later:

LABEL #1,"Hello World",50,50
...
LABEL #1,"Bye, Bye",70,70

For maximum compatibility, you might want to always proceed like explained for versions prior to version 4.0, as this way of doing will work for all Palm OS versions starting with version 3.0.
The Handspring Visor devices do not support the DESTROY statement because of what I suspect to be a bug in their Palm OS 3.x special versions.

FIELDCOPY #v|n

Copy the current selection of a NUMFIELD, TEXTFIELD or TEXTFIELD$$ to the clipboard

FIELDCUT #v|n

Copy the current selection of a NUMFIELD, TEXTFIELD or TEXTFIELD$$ to the clipboard and delete the selection from the field

FIELDPASTE #v|n

Replace the current selection in the field, if any, with the contents of the clipboard

FIELDUNDO #v|n

Undo the last change made to a NUMFIELD, TEXTFIELD or TEXTFIELD$$, if any. Changes include backspace, cut and paste.

FLUSHEVENTS [v|n]

According to the optional [v|n] parameter, offers to flush part or the entire system events queue:

if no argument was passed or if v|n is set to 0:
executes pending system events until the events queue is emptied
if v|n is set to a value in the [1...255] range:
executes a maximum of v|n system events. If the events queue is emptied before this v|n number is reached, the control is returned to your application

Notes:

In the very specific case your source code updates many GUI objects without returning the control to Palm OS with one of the DOEVENTS or WAITEVENT functions, you may get an events queue overflow (resulting in an error message and an application crash). Then insert some FLUSHEVENTS statements in your source code to have the events executed and the events queue emptied.
Flushing events can be useful in the case you develop an application which allows the user to keep pressing hard buttons and your application has difficulty to manage all its tasks in the time between two events are queued.

$ GRAFFITISHIFT 0|1, x, y

Sets or unsets the Graffiti Shift indicator at position (x,y)

Notes:

0|1 = unset|set the Graffiti Shift indicator
in the case of unsetting the Graffiti Shift, the x and y coordinates are fake

$ HIDE #v|n

Hides an object and inactivates it, but, unlike DESTROY, does not delete it

Notes:

You may unhide a hidden object with the SHOW statement
Prior to Palm OS version 3.2 there was a bug. As a consequence, this function did not set the usable bit of the object attribute data to false, so it could still redraw or respond to the pen.

$ IMAGEBUTTON #v|n1, v|n2, x, y, w, h

Creates an image button, puts image v|n2 centered in the button frame

Notes:

v|n2 is the image ID with the following images available (which automatically adapts to the color displaying capabilities of the device: high resolution color, low resolution color, gray scale or black & white):

Warning: there is no check on this image ID number as you can very well add your own customized images to your program. You may also remove or replace this set of images, please refer to the RESOURCEFILE compiling directive for further information.

KEYBOARD v|n

Pop up the system keyboard if there is a field object with the focus. The field object's text is edited directly. The v|n parameter can take the following values:

0 Alphabetical letters (abc)

1 Numerals (123)

2 Alphabetical letters with accents (Int'l)

LABEL #v|n, c|t, x, y

Creates and displays a label with c|t label.

LISTCHOICE #v|n1, c|t1/v|n2, c|t2, x, y, w, h

Creates and displays a list choice with initial c|t1 label or the v|n2 index of an item in the c|t2 list of selectable items.

When the user will tick on the LISTCHOICE, a selection of items (c|t2) will popup and, upon selection, the selected item will replace the initial label.

Notes:

to set the initial selection, you may either pass its label (c|t1) or its index (v|n2) in the list of selectable items
c|t2 is the list of selections separated by a ś character (which is CHR$(182)) with a maximum of 7 items, for example:
"choice #1śchoice #2śchoice #3"

L$="choice #1"+CHR$(182)+"choice #2"+CHR$(182)+"choice #3"

c|t2 may also be a pointer to the A$() array, starting at index A$(m) and stopping at the first empty A$() index, still with a maximum of 7 items, for example: "A$(68)" stops when A$(m)="" with m>68 and m<=74

$ MENU v|n

Loads a menu from a resource file and integrates it to your application.

Notes:

v|n is a menu ID as provided in a resource file, the resource being of type MBAR (please refer to the RESOURCEFILE compiling directive) in the range [1...999]
v|n is to be in the range [1...999] to activate the corresponding menu
If v|n is set to 0, no more menu will be integrated and the default behaviour will be restored (Default or custom AboutBox when clicking on the title)
This statement overrides the ABOUTBOX statement: when the user clicks on the Application name, your menu will be opened instead of the AboutBox. You should then implement an AboutBox (with MESSAGEBOX or NOTICEBOX) as an answer to a menu item.
As from version 5.0 of iziBasic, the menu can be managed dynamically at runtime and is no more built once at compilation time. This means that you should define your menu after the BEGIN statement to have it taken into account.

NUMFIELD #v|n, c|t, 0|1, x, y, w, h

Creates and displays a field to input numeric values, with the initial value set to c|t

Notes:

the initial value has to be passed as a TextVar, therefore you should convert your v|n to a c|t using the STR$ function
0|1 = single line|multiple lines
only numbers can be keyed in by the user, but the result is returned in a TextVar

$ OPENFORM v|n

Loads the main form or a custom modal form from a resource file and displays it on the screen.

Notes:

if v|n=0, the main form is shown. This is useful only in the case it was hidden using the CLOSEFORM instruction.
Otherwise, v|n is a form ID as provided in a resource file, the resource being of type tFRM (please refer to the RESOURCEFILE compiling directive) in the range [1...999] with the Modal flag set
If you open a custom form on top of an already opened form, the previous form will be closed before the new one is loaded and displayed. So, there is no need to explicitly close a form before opening a new one, it is only needed if you want to return to the main form.
All events occurring on objects defined in a custom form that are similar and which follow the same rules (ID in the range [1...999]) to those defined in this GUI module will be captured, except for the LISTCHOICE and POPUPCHOICE ones (Popup).
So, you should avoid using custom forms with Popups (Popups are made of a PopupTrigger and an attached List). But you may very well add them dynamically in such a form (using the LISTCHOICE and POPUPCHOICE statements), as well as any other object. Just proceed the same way as you do with any object in the main form.
One additional operation (in 3 steps) will be required for the POPUPCHOICE use which is to add:
- Step #1. a List resource in your custom form (one List resource only, whatever the number of POPUPCHOICEs you have in your custom form), with ID set to 1012, and unset its usable flag (all other parameters set as you wish, they will be overridden at run time)
- Step #2. a "fake" PopupTrigger resource, with ID set to 1011 and usable flag unset (all other parameters set as you wish, they will be overridden at run time)
- Step #3. a Popup resource, linking PopupTrigger 1011 and List 1012
Scrollbars can be included in a custom form, but they need a special treatment too: you should include up to 6 scrollbars in your form, setting their resource ID, starting from 1021 and up to 1026, and unset their usable flag (all other parameters set as you wish, they will be overridden at run time). Then, use the SCROLLBAR statement in your source code to activate them.
Another tricky thing in using OPENFORM has to do with the Palm OS version:
- With Palm OS 5: when a MBAR ID is assigned to a tFORM, calling OPENFORM automatically links the menu to the form, as expected.
- With Palm OS<5: when a MBAR ID is assigned to a tFORM, calling OPENFORM does not link the menu to the form.
This can easily be managed in your iziBasic source code:

V$=GETOSVER$
'assign menu 2 to the new form if Palm OS<5
IF V$--<"5.0" MENU 100
OPENFORM 100
'do whatever is needed with the form
CLOSEFORM
'back to main menu of main form
IF V$--<"5.0" MENU 1

POPUPCHOICE #v|n1, c|t1/v|n2, c|t2, v|n3, x, y, w, h

Creates and displays a popup list choice with initial c|t1 label or the v|n2 index of an item in the c|t2 list of selectable items.

When the user will tick on the POPUPCHOICE, a selection of items (c|t2) will popup and, upon selection, the selected item will replace the initial label.

Notes:

to set the initial selection, you may either pass its label (c|t1) or its index (v|n2) in the list of selectable items
c|t2 is the list of selections separated by a ś character (which is CHR$(182)) with no maximum number of items but the number of items you can put in the c|t2 string (so 32 one character items is the limit), for example:
"choice #1śchoice #2śchoice #3"

L$="choice #1"+CHR$(182)+"choice #2"+CHR$(182)+"choice #3"

c|t2 may also be a pointer to the A$() array, starting at index A$(n4) and stopping at the first empty A$() index, this time with a maximum of 89 items, for example: "A$(68)" stops when A$(m)="" with m>68 and m<=156
v|n3 is the number of items visible in a list, it has to be in the [1...14] range

PUSHBUTTON #v|n, c|t, 0|1, x, y, w, h

Creates and displays a push button with c|t label and defines if it is initially pushed or not (0|1 = not pushed|pushed).

RESTORESCREEN

Restores a screen which was previously saved with the SAVESCREEN statement.

SAVESCREEN

Saves the current screen to be restored later with the RESTORESCREEN statement.

SCROLLBAR #v|n1, v|n2, x, y, w, h

Creates and displays a scrollbar, putting the scroll car at position v|n2.

Notes:

There are 100 positions in the scrollbar, whatever its size, so v|n2 has to be in the [1...100] range; you may consider it as a percentage or relative position
Your application may have up to 6 scrollbars, but you will barely need more than one (usually vertical) or two (usually a vertical one and a horizontal one). Vertical scrollbars can be used whatever Palm OS version is running the device, but Palm OS 3.5 or later is required for horizontal scrollbars
Be careful that iziBasic does not check for the Palm OS version when drawing a horizontal scrollbar, so your code should manage it (see the GETOSVER$ function and the MINOSVERSION compiling directive)

SETFOCUS #v|n

Set the focus to the specified v|n TEXTFIELD or NUMFIELD object.

Notes:

You may use SETFOCUS #0 to unset the focus
See the GETFOCUS function

SETFONT v|n

Sets text font to be applied in all further objects creations and/or displayings.

The possible values for v|n are:: 0 stdFont; 1 boldFont; 2 largeFont; 3 symbolFont; 4 symbol11Font; 5 symbol7Font; 6 ledFont; 7 largeBoldFont; 8...127 some of the newer devices have additional fonts installed, and even though they are not standard, you may access them; 128 iziBasic console low resolution font; 129 iziBasic console high resolution font; 130 any personalized low resolution font that you put in a resource file; 131 any personalized high resolution font that you put in a resource file

Notes:

Unless forced by the CONSOLEFONT compiling directive, fonts 128 and 129 are only put in your program by iziBasic if they are required (use of INPUT and PRINT statements) and only one of the two will be available at runtime, depending on the screen resolution, low or high, of the device (see the HIGHRES function). Because only one is made available at runtime, you may call SETFONT with either of the 128 or 129 values.
As for your personalized fonts, the same "selection" process according to the device's screen resolution is applied. Your resources have to be of type NFNT and with the corresponding ID value, 130 or 131 (see the RESOURCEFILE compiling directive).
Would you wish to only provide a low resolution font to all types of devices, then only provide a font with ID 130 and no font with ID 131. iziBasic will know how to handle it.
If you only provide a high resolution font, the stdFont will be shown on devices with low resolution display.
PalmOS 3.1 onwards for fonts 128, 129, 130 and 131

$ SHOW #v|n

Shows a hidden object or redraws a visible object

Notes:

You may hide an object with the HIDE statement

TEXTFIELD #v|n, c|t, 0|1, x, y, w, h

Creates and displays a field to input some text, with the initial value set to c|t

Notes:

0|1 = single line|multiple lines
see the TEXTFIELD$$ statement in the MegaString chapter

TEXTSELECTOR #v|n, c|t, x, y, w, h

Creates and displays a text selector field, with the initial value set by c|t, to input some text formatted in a way that your program should handle.

Notes:

When the user ticks on a text selector, it will create an event like a button event and your program should then handle what to do with this event
The text selector use is especially convenient to call the Color, Date or Time selectors (see COLORSELECT, DATESELECT$ and TIMESELECT$ functions)

$ TITLE c|t

Sets main form title to c|t

Notes:

By default the main form title is set to the program name

$ UPDATECHOICE #v|n, c|t

Updates the selection of items in the following GUI objects: LISTCHOICE and POPUPCHOICE

Notes:

c|t is the list of selections separated by a ś character (which is CHR$(182))

$ UPDATEFIELD #v|n, c|t

Updates to c|t the text of a NUMFIELD or a TEXTFIELD with the c|t value

Notes:

using UPDATEFIELD is a way to avoid deleting (DESTROY) and rebuilding a field from scratch (this was the only way in iziBasic version 1.0)

$ UPDATELABEL #v|n, c|t

Updates to c|t a labels text created with LABEL

Notes:

this is a way to avoid deleting (DESTROY) and rebuilding a LABEL from scratch (this was the only way in iziBasic version 1.0)

$ UPDATEPOS #v|n, x, y

Updates the position of an object to (x,y)

Notes:

To avoid display rendering problems, it is usually wise to HIDE the object, update its position and then SHOW it again

$ UPDATETEXT #v|n, c|t

Updates the text of the following GUI objects: BUTTON, CHECKBOX, LISTCHOICE, POPUPCHOICE, PUSHBUTTON, TEXTSELECTOR

Notes:

this is a way to avoid deleting (DESTROY) and rebuilding an object from scratch (this was the only way in iziBasic version 1.0)

$ UPDATEVALUE #v|n1, 0|1/v|n2

Updates the value of the following GUI objects:

Notes:

this is a way to avoid deleting (DESTROY) and rebuilding one object from scratch (this was the only way in iziBasic versions prior to 4.2 for CHECKBOX and PUSHBUTTON)